<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 24. Zend_Loader</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="index.html" title="Programmer's Reference Guide">
<link rel="prev" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="next" href="zend.loader.pluginloader.html" title="24.2. Loading Plugins">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="section" href="zend.loader.html#zend.loader.load" title="24.1. Loading Files and Classes Dynamically">
<link rel="section" href="zend.loader.pluginloader.html" title="24.2. Loading Plugins">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 24. Zend_Loader</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.ldap.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="zend.loader.pluginloader.html">Next</a>
</td>
</tr>
</table></div>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="zend.loader"></a>Chapter 24. Zend_Loader</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="zend.loader.html#zend.loader.load">24.1. Loading Files and Classes Dynamically</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.loader.html#zend.loader.load.file">24.1.1. Loading Files</a></span></dt>
<dt><span class="sect2"><a href="zend.loader.html#zend.loader.load.class">24.1.2. Loading Classes</a></span></dt>
<dt><span class="sect2"><a href="zend.loader.html#zend.loader.load.isreadable">24.1.3. Testing if a File is Readable</a></span></dt>
<dt><span class="sect2"><a href="zend.loader.html#zend.loader.load.autoload">24.1.4. Using the Autoloader</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.loader.pluginloader.html">24.2. Loading Plugins</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.loader.pluginloader.html#zend.loader.pluginloader.usage">24.2.1. Basic Use Case</a></span></dt>
<dt><span class="sect2"><a href="zend.loader.pluginloader.html#zend.loader.pluginloader.paths">24.2.2. Manipulating Plugin Paths</a></span></dt>
<dt><span class="sect2"><a href="zend.loader.pluginloader.html#zend.loader.pluginloader.checks">24.2.3. Testing for Plugins and Retrieving Class Names</a></span></dt>
</dl></dd>
</dl>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.loader.load"></a>24.1. Loading Files and Classes Dynamically</h2></div></div></div>
<p>
        The Zend_Loader class includes methods to help you load files dynamically.
    </p>
<div class="tip"><table border="0" summary="Tip: Zend_Loader vs. require_once()">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td>
<th align="left">Zend_Loader vs. require_once()</th>
</tr>
<tr><td align="left" valign="top"><p>
            The <code class="code">Zend_Loader</code> methods are best used if the filename you need to
            load is variable.  For example, if it is based on a parameter from
            user input or method argument.  If you are loading a file or a
            class whose name is constant, there is no benefit to using
            <code class="code">Zend_Loader</code> over using traditional PHP functions such as
            <a href="http://php.net/require_once" target="_top"><code class="code">require_once()</code></a>.
        </p></td></tr>
</table></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.loader.load.file"></a>24.1.1. Loading Files</h3></div></div></div>
<p>
            The static method <code class="code">Zend_Loader::loadFile()</code> loads a PHP
            file.  The file loaded may contain any PHP code.
            The method is a wrapper for the PHP function
            <a href="http://php.net/include" target="_top"><code class="code">include()</code></a>.
            This method throws <code class="code">Zend_Exception</code> on failure, for example
            if the specified file does not exist.
        </p>
<div class="example">
<a name="zend.loader.load.file.example"></a><p class="title"><b>Example 24.1. Example of loadFile() method</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
Zend_Loader::loadFile($filename, $dirs=null, $once=false);
            </pre></div>
</div>
<br class="example-break"><p>
            The <code class="code">$filename</code> argument specifies the filename to load,
            which must not contain any path information.
            A security check is performed on <code class="code">$filename</code>.
            The <code class="code">$filename</code> may only contain alphanumeric characters,
            dashes ("-"), underscores ("_"), or periods (".").
            No such restriction is placed on the <code class="code">$dirs</code> argument.
        </p>
<p>
            The <code class="code">$dirs</code> argument specifies directories to search for
            the file.  If <code class="code">NULL</code>, only the <code class="code">include_path</code>
            is searched.  If a string or an array, the directory or directories
            specified will be searched, and then the <code class="code">include_path</code>.
        </p>
<p>
            The <code class="code">$once</code> argument is a boolean.  If <code class="code">TRUE</code>,
            <code class="code">Zend_Loader::loadFile()</code> uses the PHP function
            <a href="http://php.net/include" target="_top"><code class="code">include_once()</code></a>
            for loading the file, otherwise the PHP function
            <a href="http://php.net/include_once" target="_top"><code class="code">include()</code></a>
            is used.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.loader.load.class"></a>24.1.2. Loading Classes</h3></div></div></div>
<p>
            The static method <code class="code">Zend_Loader::loadClass($class, $dirs)</code>
            loads a PHP file and then checks for the existance of the class.
        </p>
<div class="example">
<a name="zend.loader.load.class.example"></a><p class="title"><b>Example 24.2. Example of loadClass() method</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
Zend_Loader::loadClass('Container_Tree',
    array(
        '/home/production/mylib',
        '/home/production/myapp'
    )
);
            </pre></div>
</div>
<br class="example-break"><p>
            The string specifying the class is converted to a relative path
            by substituting directory separates for underscores, and appending
            '.php'.  In the example above, 'Container_Tree' becomes 'Container/Tree.php'.
        </p>
<p>
            If <code class="code">$dirs</code> is a string or an array,
            <code class="code">Zend_Loader::loadClass()</code> searches the directories in
            the order supplied.  The first matching file is loaded.  If the file
            does not exist in the specified <code class="code">$dirs</code>, then the
            <code class="code">include_path</code> for the PHP environment is searched.
        </p>
<p>
            If the file is not found or the class does not exist after the load,
            <code class="code">Zend_Loader::loadClass()</code> throws a <code class="code">Zend_Exception</code>.
        </p>
<p>
            <code class="code">Zend_Loader::loadFile()</code> is used for loading, so the
            class name may only contain alphanumeric characters and the hyphen
            ('-'), underscore ('_'), and period ('.').
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.loader.load.isreadable"></a>24.1.3. Testing if a File is Readable</h3></div></div></div>
<p>
            The static method <code class="code">Zend_Loader::isReadable($pathname)</code>
            returns <code class="code">TRUE</code> if a file at the specified pathname exists
            and is readable, <code class="code">FALSE</code> otherwise.
        </p>
<div class="example">
<a name="zend.loader.load.isreadable.example"></a><p class="title"><b>Example 24.3. Example of isReadable() method</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
if (Zend_Loader::isReadable($filename)) {
    // do something with $filename
}
            </pre></div>
</div>
<br class="example-break"><p>
            The <code class="code">$filename</code> argument specifies the filename to
            check.  This may contain path information.
            This method is a wrapper for the PHP function
            <a href="http://php.net/is_readable" target="_top"><code class="code">is_readable()</code></a>.
            The PHP function does not search the <code class="code">include_path</code>,
            while <code class="code">Zend_Loader::isReadable()</code> does.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.loader.load.autoload"></a>24.1.4. Using the Autoloader</h3></div></div></div>
<p>
            The <code class="code">Zend_Loader</code> class contains a method you can register with the
            PHP SPL autoloader.  <code class="code">Zend_Loader::autoload()</code> is the
            callback method.  As a convenience, <code class="code">Zend_Loader</code> provides the
            <code class="code">registerAutoload()</code> function register its
            <code class="code">autoload()</code> method.  If the <code class="code">spl_autoload</code>
            extension is not present in your PHP environment, then
            <code class="code">registerAutoload()</code> method throws a <code class="code">Zend_Exception</code>.
        </p>
<div class="example">
<a name="zend.loader.load.autoload.example"></a><p class="title"><b>Example 24.4. Example of registering the autoloader callback method</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
Zend_Loader::registerAutoload();
            </pre></div>
</div>
<br class="example-break"><p>
            After registering the Zend Framework autoload callback, you can
            reference classes from the Zend Framework without having to load
            them explicitly.  The <code class="code">autoload()</code> method uses
            <code class="code">Zend_Loader::loadClass()</code> automatically when you
            reference a class.
        </p>
<p>
            If you have extended the <code class="code">Zend_Loader</code> class, you can give an
            optional argument to <code class="code">registerAutoload()</code>, to specify
            the class from which to register an <code class="code">autoload()</code> method.
        </p>
<div class="example">
<a name="zend.loader.load.autoload.example-extended"></a><p class="title"><b>Example 24.5. Example of registering the autoload callback method from an
                extended class</b></p>
<div class="example-contents">
<p>
                Because of the semantics of static function references in PHP,
                you must implement code for both <code class="code">loadClass()</code>
                and <code class="code">autoload()</code>, and the <code class="code">autoload()</code>
                must call <code class="code">self::loadClass()</code>.  If your
                <code class="code">autoload()</code> method delegates to its parent to
                call <code class="code">self::loadClass()</code>, then it calls the
                method of that name in the parent class, not the subclass.
            </p>
<pre class="programlisting">&lt;?php
class My_Loader extends Zend_Loader
{
    public static function loadClass($class, $dirs = null)
    {
        parent::loadClass($class, $dirs);
    }

    public static function autoload($class)
    {
        try {
            self::loadClass($class);
            return $class;
        } catch (Exception $e) {
            return false;
        }
    }
}

Zend_Loader::registerAutoload('My_Loader');
            </pre>
</div>
</div>
<br class="example-break"><p>
            You can remove an autoload callback.  The
            <code class="code">registerAutoload()</code> has an optional second argument,
            which is <code class="code">true</code> by default.  If this argument is
            <code class="code">false</code>, the autoload callback in unregistered from the
            SPL autoload stack instead of registered.
        </p>
</div>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.ldap.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="zend.loader.pluginloader.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 23. Zend_Ldap </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 24.2. Loading Plugins</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
